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Wave  Data  Processing  and  Analysis, 
Part  2:  Codes  for  Coupling  GenCade 

and  CMS-Wave 

by  Rusty  Permenter,  Kenneth  J.  Connell,  and  Zeki  Demirbilek 


PURPOSE:  This  Coastal  and  Hydraulics  Engineering  Technical  Note  (CHETN)  describes  an 
application  of  wave  data  processing  codes  to  generate  representative  wave  conditions 
required  as  input  to  GenCade.  This  is  the  second  CHETN  in  a  two-part  series  detailing  the 
process  of  coupling  CMS-Wave  with  GenCade.  This  CHETN  focuses  on  compiling  binned  wave 
conditions  for  input  to  CMS-Wave  and  the  processing  of  CMS-Wave  output  files  to  generate 
input  wave  information  for  GenCade.  The  toolkit  and  an  example  dataset  can  be  downloaded 
from  h  ttp://cirp.  usace.  armv.mil/products/?tab=4. 

DESCRIPTION  OF  CODES:  The  approach  used  to  integrate  detailed  nearshore  wave 
information  generated  using  CMS-Wave  into  GenCade  involves  a  set  of  MATLAB  routines  that 
transform  and  bin-sort  offshore  wave  information  to  develop  representative  input  wave 
conditions  for  CMS-Wave.  A  second  executable  program  (CMS2MAP.exe)  is  provided  for 
processing  the  CMS-Wave  output  files  for  input  to  GenCade.  The  details  of  the  MATLAB 
routines  were  described  in  Part  1  (CHETN-IV-97).  Part  2  demonstrates  the  insertion  of  a 
wave  data  set  into  CMS-Wave  and  the  subsequent  processing  of  the  CMS-Wave  results.  The 
Fortran  executable  (cms2map.exe)  allows  the  user  to  convert  a  set  of  representative  conditions  to  a 
time  series  input  for  GenCade.  After  a  CMS-Wave  simulation  is  completed,  the  user  can  run 
cms2map.exe  to  convert  the  SMS  selhts.out  file  (or  Lout)  to  a  time  series  of  wave  conditions  for 
input  to  GenCade.  This  executable  requires  the  use  of  observation  station  output  from  CMS-Wave 
either  as  binned  data  or  as  a  time  series  of  wave  conditions.  As  described  in  Part  1,  the  user 
provides  a  set  of  binned  wave  conditions  and  associated  probabilities  developed  using  the 
MATLAB  routines.  The  purpose  of  binning  the  data  is  to  reduce  the  computational  effort  required 
to  run  a  full  time  series  in  CMS-Wave.  A  cursory  description  of  CMS-Wave  is  provided  here,  for 
details  please  see  CMS-Wave  references  (Lin  et  al.  2011;  Lin  et  al.  2008).  The  example  shown 
below  continues  the  example  from  the  Part  1  CHETN. 

Steps  for  Using  Codes.  There  are  five  main  tasks  (A-E)  involved  in  integrating  nearshore 
wave  information  generated  using  CMS-Wave  into  GenCade.  These  are  summarized  below. 
Before  applying  the  Fortran  code,  the  user  needs  to  compile  incident  wave  spectra  for  CMS- 
Wave  and  designate  wave  save  stations. 

A.  Generate  Incident  Spectra  for  CMS-Wave 

To  run  CMS-Wave,  incident  wave  spectra  must  be  generated  for  each  wave  condition.  The 
input  wave  conditions  are  the  binned  wave  conditions  developed  by  the  MATLAB  code 
described  in  the  Part  1  CHETN.  The  binned  wave  conditions  are  stored  in  the  file 
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WaveBin_Table_Over_MinCount_Threshold.dat.  The  steps  for  using  SMS  to  generate  CMS- 
Wave  incident  spectra  from  the  binned  wave  conditions  are  given  as  follows: 

Step  1.  Under  the  CMS-Wave  menu,  select  Spectral  Energy. 

Step  2.  Select  Create  Grid  or  upload  an  existing  spectral  grid  using  the  import  grid  tab. 

Step  3.  Specify  the  number  of  frequency  bin  walls  (30  walls  results  in  29  bins),  frequency 
increment  (Delta),  and  minimum  and  maximum  frequencies.  In  Figure  1,  the  frequency  range 
corresponds  to  wave  periods  of  3.0  sec  to  25  sec.  The  angle  distribution  is  not  adjustable  in 
CMS-Wave. 


Figure  1.  Spectral  energy  grid  options. 

Step  4.  Once  the  new  spectral  grid  is  created  right  click  on  the  New_Spectral_Grid  and 
select  Generate  Spectra  from  the  menu. 

Step  5.  Copy  and  paste  the  values  of  wave  heights,  periods,  and  directions  from  the 
WaveBin_Table_Over_MinCount_Threshold.dat  into  the  corresponding  columns.  Use  of 
default  values  listed  in  Figure  2  are  recommended  for  Gamma  and  nn  specifications.  After 
completing  the  input  table,  click  the  Generate  button. 

Step  6.  Export  the  spectra  by  clicking  on  the  Export  Spectra  in  the  spectra  generator.  Be 
sure  that  the  spectra  file  name  matches  the  file  name  used  in  the  CMS-Wave  *.sim  file. 

B.  Select  CMS-Wave  Observation  Cells 

Step  1.  Determine  the  location  where  breaking  waves  occur  in  the  target  area.  Wave 
observation  stations  should  be  positioned  immediately  offshore  of  the  breaking  depth  of  the 
largest  wave  (approximately  0.8  of  the  significant  wave  height). 
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Spectral  Defaults 

Double-click  a  row  of  values  to 
update  selected  spreadsheet 
row(s): 
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Figure  2.  Spectral  Defaults 


Step  2.  In  the  Cartesian  grid  module  of  SMS,  select  the  Cell  tool  ™  for  specifying  grid  cells 
to  serve  as  observation  (monitoring)  stations. 

Step  3.  Press  the  Shift  key  to  select  multiple  cells  along  the  desired  contours  or  depths  for 
observation  stations.  The  use  of  multiple  cells  along  the  length  of  the  GenCade  grid  captures 
the  effects  of  complex  nearshore  bathymetry  on  wave  conditions. 

Step  4.  Right  click  on  the  screen  to  display  the  Cell  Attributes  window  (see  Figure  3).  Change 
the  Cell  Type  from  Default  to  Monitoring  station. 


Figure  3.  Cell  attributes  window. 
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C.  Convert  CMS-Wave  Output  to  Representative  Time-Series  Data  for  Input  to 
GenCade 


Step  1.  Inspect  wave  heights  in  the  selhts.out  (or  *.out)  file  produced  by  the  CMS-Wave  to 
ensure  wave  heights  at  each  monitoring  cell  are  reasonable.  Confirm  the  number  of  rows  in 
the  file  equal  to  the  number  of  observation  stations  multiplied  by  the  number  of  wave  events. 
If  the  *.out  file  is  not  deleted  prior  to  subsequent  CMS-Wave  runs,  results  will  be  appended  to 
the  existing  file  and  can  lead  to  erroneous  wave  data  in  GenCade  simulations. 

Step  2.  Prepare  two  input  files  for  cms2map.exe: 

•  cms2map.ctrl:  The  control  file  that  assigns  input  and  output  file  names,  directory 
paths,  and  input  flags  as  given  in  Table  1. 

•  JP_MultipleTimebin_Probability.dat:  An  array  of  percent  occurrence  values.  One 
value  for  each  time  bin  for  every  CMS-Wave  event  simulated. 


Table  1.  Example  of  CMS2MAP  .Ctrl  file. 

a 

1 

#  CMS-Wave  control  file  (*.sim): 

a 

FORMATOUT:  SMS_Map_Wave_File 

i 

SIMFILE:  Demol.sim 

!  [if FORMATOUT  =  SMSJVIap_Wave_File] 

# - 

!  Output  Time  Series  SMS  *.map  file: 

#  CMS-Wave  options  file  (*.std): 

1 _ 

# - 

MAPFILE:  Demo  1  waves. map 

STDFILE:  Demol.std 

1 _ 

# - 

!  Output  time  series  start  date  <yyyymmddHHMMSS>: 

#  CMS-Wave  depth  file  (*.dep): 

1 _ 

# - 

STARTDATE:  19990101000000 

DEPFILE:  Demol.dep 

1 _ 

# - 

!  Output  time  series  timestep  (hours)  <3>: 

#  CMS-Wave  station  output  file  (selhts.out): 

1 _ 

# - 

TIMESTEPOUT:  3.0 

SELHTSOUTFILE:  selhts.out 

1 _ 

!  Flag  for  CMS  mode: 

!  Output  time  series  length  (hours)  <8760>: 

!  <1>  =  time-series  (process-based)  mode; 

1 _ 

!  <0>  =  steady  state  mode 

TSOUTLENGTH:  8760.0  > 

CMSTSFLAG:  0 

!  OPTIONAL  INPUT  FILE 

!  [if  CMSTSFLAG  =  0] 

1 _ 

!  [if FORMATOUT  =  GenCade_WaveJTle] 

!  Optional  %  Frequency  of  Occurrence  file: 
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1 _ 

!  Existing  GenCade  Control  Filename: 

FREQFILE:  JP  MultipleTimebin_Probability.dat 

1 _ 

1 _ 

!  GENFILEIN:  Region_merge_08tst.gen 

!  [if  CMSTSFLAG  =  0] 

!  Number  of  time  periods  to  distribute  output 

,***********************«^ 

!  time  series  over  <1>: 

!  !  IF  there  is  no  existing  *.gen  file  add  the 

!  (e.g.  Annually  =  1;  Seasonally  =4;  Monthly  =  12) 

!  !  following  cards  to  this  control  file: 

1 _ 

J 

NTIMEBINS:  2 

1  ! _ 

! _ 

!  [if  CMSTSFLAG  =  0] 

!  !  GenCade  Grid  Origin: 

!  Flag  for  random  temporal  distribution: 

!  X0:  250000.0 

!  <1>  =  randomly  distributed; 

!  <0>  =  same  order  as  input  wave  events 

!  Y0:  165000.0 

! 

RANDOMFLAG:  1 

1  1 _ 

!  !  GenCade  Grid  Azimuth: 

1  1 _ 

1 _ 

!  Flag  for  output  fonnat: 

!  AZIMUTHGEN:  8.0 

!  <SMS  Map  Wave  File>  =  SMS  Map  File; 

!  !  AZIMUTHGEN:  equal 

!  <GenCade  Wave  File>  =  GenCade  Wave  Files 

!  If  you  want  it  to  be  the  same  as  the  CMS-Wave  azimuth 

i  i _ 

!  !  Number  of  GenCade  Grid  Cells: 

!  NX:  205 

! 

i  i _ 

!  !  GenCade  Grid  Cell  Resolution/Width: 

!  DX:  300.000000 

The  JP_MultipleTimebin_Probability.dat  file  can  be  generated  using  the  code  discussed  in  the 
Part  1  CHETN.  Each  row  of  data  contains  the  percent  occurrence  for  each  binned  wave 
condition.  The  columns  of  the  file  represent  the  time  bins  for  each  binned  wave  condition. 
For  the  example  shown  in  Figure  3,  the  percent  occurrence  file  has  two  wave  conditions  each 
binned  for  half  a  year.  The  sum  of  the  percents  is  less  than  100  due  to  calm  periods. 

For  preparing  a  new  cms2map.ctrl  file  (see  Table  1),  the  user  may  open  a  new  Notepad  file  or 
use  the  demonstration  *.ctrl  file  (template)  available  from  the  website.  In  the  example  file 
(Table  1),  the  lines  that  begin  with  either  an  "!"  or  a  "#"  are  commented  out,  and  are  placed 
within  the  file  for  clarity,  or  to  show  cards  turned  off  for  this  application.  The  example  shows 
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the  cms2map.exe  writing  directly  to  a  .map  file  instead  of  a  GenCade  file.  To  create  a  new 
GenCade  file,  the  additional  cards  required  would  need  to  be  turned  on  (e.g.,  remove  the  !)  in 
the  *.ctrl.  For  each  card,  the  user  can  type  the  card  name  with  a  colon  followed  by  the  desired 
parameter  value.  The  first  four  cards  are  the  file  names  for  input  files  for  the  CMS-Wave  run 
(the  full  file  name  does  not  need  to  be  used  if  all  input  files  and  the  .Ctrl  file  are  in  the  same 
folder).  CMSTSFLAG  specifies  whether  the  user  wants  to  order  the  waves  calculated  by  CMS- 
Wave  (1)  or  to  use  frequency  of  occurrence  values  to  distribute  the  waves  (0).  If  0  is  selected, 
a  frequency  of  occurrence  file  must  be  generated  to  include  the  number  of  occurrences  for 
each  wave  event  and  time  bin  used  in  CMS-Wave.  The  frequency  of  occurrence  should  be 
listed  as  a  percent;  the  code  inserts  calm  wave  conditions  (0  m  wave  heights)  until  the  total 
frequency  reaches  100  percent.  The  "number  of  time  bins"  card  is  used  to  read  the 
JP_MultipleTimebin_Probability.dat  file  produced  by  the  MATLAB  codes.  RANDOMFLAG 
allows  the  user  to  either  randomly  distribute  the  wave  events  (1)  or  use  the  same  order  as 
the  input  wave  events  in  CMS-Wave  (0). 


Figure  3.  Example  of  percent 
occurrence  file. 

The  next  section  of  the  CMS2MAP.ctrl  file  specifies  the  output  for  either  a  *.map  file  or  a 
GenCade  *.gen  file.  First,  the  user  specifies  the  output  file  desired;  SMS_Map_Wave_File 
signifies  a  map  file  and  GenCade_Wave_File  signifies  a  GenCade  control  file.  If  a  map  file  is 
selected,  the  next  card  must  be  the  desired  file  name  for  the  *.map  file.  If  a  GenCade  file  is 
selected,  the  user  must  specify  either  an  existing  GenCade  control  file  (*.gen  file)or  create  a 
GenCade  control  file 

The  next  three  cards  specify  the  start  date,  time  step,  and  time-series  length,  respectively.  If 
the  user  has  an  existing  *.gen  file,  GENFILEIN  specifies  the  file  name  of  the  input  file.  If  there 
is  not  an  existing  GenCade  *.gen  file,  the  user  can  specify  a  new  file  by  adding  it  to  the  last 
section  of  the  *.ctrl  file.  The  grid  origin  is  specified  by  specifying  the  easting  as  X0  and  the 
northing  as  Y0,  the  azimuth  is  either  specified  or  set  to  be  the  same  as  the  CMS-Wave  grid. 
The  number  and  size  of  the  grid  cells  are  specified  with  the  NX  and  DX,  respectively. 

To  execute  cms2map.exe,  place  the  cms2map.ctrl,  cms2map.exe,  and  CMS-Wave  project 
files  in  the  same  folder  and  launch  the  executable  by  double-clicking  on  it.  The  executable 
may  also  be  run  in  the  command  prompt  (see  Figure  4). 
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c ms 2 nap 


Build:  02  AUG  2012 
cms2map.exe 

PURPOSE: 

Converts  CMS -Wave  station  output  data  (selhts.out) 
to  either: 

1>  SMS  *.map  file  for  GenCade  wave  input  from 
SMS  Map  Module;  or 

2>  GenCade  *.gen  and  *.wave  files  for  direct 
GenCade  wave  input . 


Output  time  series  timestep  <hours >:  3.000000 

Length  of  output  time  series  (hours >:  8760.000 

Number  of  time  periods  to  distribute  output  time  series  over:  2 

Start  Date  &  Time  (yyyynmddHHMMSS):  19990101000000 

Flag  for  CMS  mode: 

<1>  =  time-series  mode;  (0>  =  steady  state  mode:  0 

Flag  for  random  temporal  distribution: 

(1)  =  randomly  distributed;  (0>  =  same  order  as  input  waves:  1 

Output  format: 

(SMS _Map_Ua v e _F i le >  =  SMS  Map  File; 

(GenCade_Uave_File>  =  GenCade  Wave  Files:  SMS_Map_Uave_File 
Output  SMS  time  series  file  name:  Demol waves .map 


Loading  CMS -Wave  *.sim  file:  Demol. sim 
Loading  CMS -Wave  *.std  file:  Demol. std 
Loading  CMS -Wave  selhts.out  file:  selhts.out 
Loading  CMS -Wave  *.dep  file:  Demol. dep 

Loading  v.  frequency  of  occurrence  file:  JP_MultipleTimebin_Probability.dat 


Number  of  wave  observation  stations:  19 


Number  of  input  wave  events:  3 

Number  of  output  wave  events:  2920 


Wave  model  grid  origin: 

X  (Easting):  329492.636700000 

V  (Northing):  3337124.55930000 

Wave  model  grid  rotation  azimuth  (deg):  108.700000000000 


Figure  4.  Executing  CMS2MAP  in  command  prompt. 

D.  Convert  representative  time  series  to  GenCade  wave  forcing  input 

Step  1.  cms2map.exe  does  two  things:  1)  produces  annual  wave  data  time  series  based  on 
the  frequency  of  occurrence  of  the  input  wave  events,  and  2)  writes  a  *  map  file  for  GenCade 
application  in  SMS. 

Step  2.  Load  the  *.map  file  to  SMS  as  input  to  GenCade.  An  uploaded  *.map  file  is  shown  in 
Figure  5  over  the  bathymetry  for  Ship  Island. 
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Figure  5.  Multiple  Wave  Gauges  along  Ship  Island 


E.  GenCade  Setup  and  Execution 

Wave  input  files  for  a  GenCade  simulation  are  now  complete  and  GenCade  can  be  run. 
Further  information  on  the  execution  of  Gencade  can  be  found  in  the  user’s  guide  (Frey  et  al. 
2012).  Develop  a  new  case  in  the  GenCade  conceptual  model,  convert  the  case  to  a  GenCade 
domain,  finalize  input  parameters,  select  the  GenCade  menu,  and  select  <Run  GenCade... >. 
The  new  wave  map  files  may  be  merged  with  existing  map  files  by  right-clicking  on  the  map 
coverage  and  selecting  merge  coverages. 

SUMMARY:  This  CHETN  describes  a  Fortran  executable  used  to  develop  representative 
wave  climate  datasets  for  a  GenCade  application  as  wave  forcing  from  representative  CMS- 
Wave  cases.  The  binning  of  wave  conditions  for  CMS-Wave  modeling  is  described  in  the  Part 
1  CHETN.  In  the  future,  the  wave  data  processing  codes  will  be  further  developed  and 
integrated  with  other  existing  tools  and  GUIs.  The  guidance  provided  is  anticipated  to  change 
and  users  should  consult  the  Coastal  Inlets  Research  Program  (CIRP)  website 
f cirp.usace.army.mil )  and  the  CIRP  wiki  (cirp.usace.army.mil/wikQ  for  additional  information. 
The  codes  and  example  data  set  discussed  herein  can  be  downloaded  from: 
http://cirp.usace.army.mil/products/?tab=4. 

POINTS  OF  CONTACT:  This  CHETN  was  prepared  as  part  of  the  Coastal  Inlets  Research 
Program  (CIRP)  and  was  written  by  Rusty  Permenter  (Rustv.L.Permenter&usace.armv.mil. 
601-634-2089)  of  the  US  Army  Engineer  Research  and  Development  Center  (ERDC),  Coastal 
and  Hydraulics  Laboratory  (CHL)  and  Kenneth  J.  Connell  (Kenneth  Connell&golder.com )  of 
Golder  Associates,  Inc.  Ashley  Frey  and  Lihwa  Lin  provided  peer-review  of  this  publication. 
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For  information  about  CIRP,  please  contact  the  CIRP  Program  Manager,  Dr.  Julie  Dean  Rosati 

(251-694-3719)  or  by  email  f Julie. D.Rosati&usace.army.mil).  This  CHETN  should  be 

referenced  as  follows: 

Permenter,  R.,  K.  J.  Connell,  and  Z.  Demirbilek.  2013.  Wave  data  processing 
and  analysis,  Part  2:  Codes  for  Coupling  GenCade  and  CMS-Wave.  ERDC/CHL 
CHETN-IV-98.  Vicksburg,  MS:  US  Army  Engineer  Research  and  Development 
Center. 
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